operator delete

ordinary (1)	void operator delete (void* ptr) throw();
nothrow (2)	void operator delete (void* ptr, const std::nothrow_t& nothrow_constant) throw();
placement (3)	void operator delete (void* ptr, void* voidptr2) throw();

ordinary (1)	void operator delete (void* ptr) noexcept;
nothrow (2)	void operator delete (void* ptr, const std::nothrow_t& nothrow_constant) noexcept;
placement (3)	void operator delete (void* ptr, void* voidptr2) noexcept;

ordinary (1)	void operator delete (void* ptr) noexcept;
nothrow (2)	void operator delete (void* ptr, const std::nothrow_t& nothrow_constant) noexcept;
placement (3)	void operator delete (void* ptr, void* voidptr2) noexcept;
with size (4)	void operator delete (void* ptr, std::size_t size) noexcept;
nothrow with size (5)	void operator delete (void* ptr, std::size_t size, const std::nothrow_t& nothrow_constant) noexcept;

Deallocate storage space

Default deallocation functions (single-object form).

(1) ordinary delete: Deallocates the memory block pointed by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new and rendering that pointer location invalid.
(2) nothrow delete: Same as above (1).
(3) placement delete: Does nothing.

(1) ordinary delete: Deallocates the memory block pointed by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new and rendering that pointer location invalid.
(2) nothrow delete: Same as above (1).
The default definition calls the first version (1): ::operator delete(ptr).
(3) placement delete: Does nothing.

(1) ordinary delete: Deallocates the memory block pointed by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new and rendering that pointer location invalid.
(2) nothrow delete: Same as above (1).
The default definition calls the first version (1): ::operator delete(ptr).
(3) placement delete: Does nothing.
(4) (5) with size: Same as (1) and (2) respectivelly.
The default definition simply calls the corresponding version: either (1) or (2).
They provide an optimization point for custom implementations: they are called with the same size argument used in the call to the corresponding allocation function.

Note that if one of the signatures with size is replaced, its corresponsing version without size shall also be replaced (and the other way around). I.e.: If either (1) or (4) is replaced, both shall be replaced. Likewise, if either (2) or (5) is replaced, both shall be replaced.

The default allocation and deallocation functions are special components of the standard library; They have the following unique properties:

Global: All overloads of operator delete are declared in the global namespace, not within the std namespace.
Implicit: The deallocating versions (i.e., all but (3)) are implicitly declared in every translation unit of a C++ program, no matter whether header <new> is included or not.
Replaceable: The deallocating versions (i.e., all but (3)) are also replaceable: A program may provide its own definition that replaces the one provided by default or can overload it for specific types. The custom definition shall deallocate the storage referenced by ptr.

operator delete is a regular function that can be called explicitly just as any other function. But in C++, delete is an operator with a very specific behavior: An expression with the delete operator, first calls the appropriate destructor (for class types), and then calls a deallocation function.

The deallocation function for a class object is a member function named operator delete, if it exists. In all other cases it is a global function operator delete (i.e., this function -- or a more specific overload). If the delete expression is preceded by the scope operator (i.e., ::operator delete), only global deallocation functions are considered.

delete expressions that use global deallocation functions, always call single-argument signatures (such as (1)).

delete expressions that use global deallocation functions always use the signature that takes either a pointer (such as (1)), or a pointer and a size (such as (4)). Preferring always the version with size (4), unless an overload provides a better match for the pointer type.

The other signatures ((2) and (3)) are never called by a delete-expression (the delete operator always calls the ordinary version of this function, and exactly once for each of its arguments). These other signatures are only called automatically by a new-expression when their object construction fails (e.g., if the constructor of an object throws while being constructed by a new-expression with nothrow, the matching operator delete function accepting a nothrow argument is called).

Non-member deallocation functions shall not be declared in a namespace scope other than the global namespace.

Parameters

ptr: A pointer to the memory block to be released, type-casted to a void*.
If this is a null-pointer, the function does nothing.

If not null, this pointer value should have been returned by a previous call to operator new, and have not yet been released by a previous call to this function.

If not null, this pointer value should have been returned by a previous call to operator new, and have not yet been released by a previous call to this function.
If the implementation has strict pointer safety, this pointer shall also be a safely-derived pointer.
nothrow_constant: The constant nothrow. This parameter is ignored in the default definition.
nothrow_t is the type of constant nothrow.
voidptr2: A void pointer. The value is ignored in the default definition.
size: The first argument passed to the allocation function when the memory block was allocated.
std::size_t is an unsigned integral type.

Return value

none

Example

// operator delete example
#include <iostream>     // std::cout

struct MyClass {
  MyClass() {std::cout <<"MyClass constructed\n";}
  ~MyClass() {std::cout <<"MyClass destroyed\n";}
};

int main () {
  MyClass * pt = new (std::nothrow) MyClass;
  delete pt;    // implicitly calls ::operator delete(pt)

  return 0;
}

Output:


MyClass constructed
MyClass destroyed

Data races

Modifies the storage referenced by ptr.
Calls to allocation and deallocation functions that reuse the same unit of storage shall occur in a single total order where each deallocation happens before the next allocation.
This shall also apply to the observable behavior of custom replacements for this function.

Exception safety

No-throw guarantee: this function never throws exceptions.

Notice that an invalid value of ptr causes undefined behavior.

Notice that either an invalid value of ptr, or a value for size that does not match the one passed to the allocation function, causes undefined behavior.

functions (global namespace)

functions (std namespace)

types